/*  libFLAC - Free Lossless Audio Codec library
    Copyright (C) 2004-2009  Josh Coalson
    Copyright (C) 2011-2016  Xiph.Org Foundation

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    - Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

    - Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

    - Neither the name of the Xiph.org Foundation nor the names of its
    contributors may be used to endorse or promote products derived from
    this software without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

#ifndef FLAC__CALLBACK_H
#define FLAC__CALLBACK_H

#include "ordinals.h"
#include <stdlib.h> /* for size_t */

/** \file include/FLAC/callback.h

    \brief
    This module defines the structures for describing I/O callbacks
    to the other FLAC interfaces.

    See the detailed documentation for callbacks in the
    \link flac_callbacks callbacks \endlink module.
*/

/** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures
    \ingroup flac

    \brief
    This module defines the structures for describing I/O callbacks
    to the other FLAC interfaces.

    The purpose of the I/O callback functions is to create a common way
    for the metadata interfaces to handle I/O.

    Originally the metadata interfaces required filenames as the way of
    specifying FLAC files to operate on.  This is problematic in some
    environments so there is an additional option to specify a set of
    callbacks for doing I/O on the FLAC file, instead of the filename.

    In addition to the callbacks, a FLAC__IOHandle type is defined as an
    opaque structure for a data source.

    The callback function prototypes are similar (but not identical) to the
    stdio functions fread, fwrite, fseek, ftell, feof, and fclose.  If you use
    stdio streams to implement the callbacks, you can pass fread, fwrite, and
    fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or
    FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle
    is required.  \warning You generally CANNOT directly use fseek or ftell
    for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems
    these use 32-bit offsets and FLAC requires 64-bit offsets to deal with
    large files.  You will have to find an equivalent function (e.g. ftello),
    or write a wrapper.  The same is true for feof() since this is usually
    implemented as a macro, not as a function whose address can be taken.

    \{
*/

#ifdef __cplusplus
extern "C" {
#endif

/** This is the opaque handle type used by the callbacks.  Typically
    this is a \c FILE* or address of a file descriptor.
*/
typedef void* FLAC__IOHandle;

/** Signature for the read callback.
    The signature and semantics match POSIX fread() implementations
    and can generally be used interchangeably.

    \param  ptr      The address of the read buffer.
    \param  size     The size of the records to be read.
    \param  nmemb    The number of records to be read.
    \param  handle   The handle to the data source.
    \retval size_t
      The number of records read.
*/
typedef size_t (*FLAC__IOCallback_Read)(void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);

/** Signature for the write callback.
    The signature and semantics match POSIX fwrite() implementations
    and can generally be used interchangeably.

    \param  ptr      The address of the write buffer.
    \param  size     The size of the records to be written.
    \param  nmemb    The number of records to be written.
    \param  handle   The handle to the data source.
    \retval size_t
      The number of records written.
*/
typedef size_t (*FLAC__IOCallback_Write)(const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);

/** Signature for the seek callback.
    The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT
    EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long'
    and 32-bits wide.

    \param  handle   The handle to the data source.
    \param  offset   The new position, relative to \a whence
    \param  whence   \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END
    \retval int
      \c 0 on success, \c -1 on error.
*/
typedef int (*FLAC__IOCallback_Seek)(FLAC__IOHandle handle, FLAC__int64 offset, int whence);

/** Signature for the tell callback.
    The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT
    EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long'
    and 32-bits wide.

    \param  handle   The handle to the data source.
    \retval FLAC__int64
      The current position on success, \c -1 on error.
*/
typedef FLAC__int64(*FLAC__IOCallback_Tell)(FLAC__IOHandle handle);

/** Signature for the EOF callback.
    The signature and semantics mostly match POSIX feof() but WATCHOUT:
    on many systems, feof() is a macro, so in this case a wrapper function
    must be provided instead.

    \param  handle   The handle to the data source.
    \retval int
      \c 0 if not at end of file, nonzero if at end of file.
*/
typedef int (*FLAC__IOCallback_Eof)(FLAC__IOHandle handle);

/** Signature for the close callback.
    The signature and semantics match POSIX fclose() implementations
    and can generally be used interchangeably.

    \param  handle   The handle to the data source.
    \retval int
      \c 0 on success, \c EOF on error.
*/
typedef int (*FLAC__IOCallback_Close)(FLAC__IOHandle handle);

/** A structure for holding a set of callbacks.
    Each FLAC interface that requires a FLAC__IOCallbacks structure will
    describe which of the callbacks are required.  The ones that are not
    required may be set to NULL.

    If the seek requirement for an interface is optional, you can signify that
    a data source is not seekable by setting the \a seek field to \c NULL.
*/
typedef struct {
    FLAC__IOCallback_Read read;
    FLAC__IOCallback_Write write;
    FLAC__IOCallback_Seek seek;
    FLAC__IOCallback_Tell tell;
    FLAC__IOCallback_Eof eof;
    FLAC__IOCallback_Close close;
} FLAC__IOCallbacks;

/* \} */

#ifdef __cplusplus
}
#endif

#endif
